Skip to content

feat(Tensors): Tensor, Species.pure and the group action Species.tensorRep - #2084

Open
pariandrea wants to merge 6 commits into
leanprover-community:masterfrom
pariandrea:tensors/stack-02-tensor
Open

pariandrea wants to merge 6 commits into
leanprover-community:masterfrom
pariandrea:tensors/stack-02-tensor

Conversation

@pariandrea

Copy link
Copy Markdown
Contributor

Second piece of the stack for #2014, after #2049. It introduces the tensors of a species and the
group action on them.

This code was written with AI assistance, specifically Claude and ChatGPT.

Design

  • Tensors on any index type. The tensors with colors c : ι → Color K are Mathlib's
    ⨂[k] i, V (c i), for any index type ι, not only Fin n. Tensor S c is a def, so its type
    keeps the species and the colors. It sits at the root, so its lemmas live in the library
    namespace Tensor, as TensorProduct does in Mathlib.
  • Pure tensors are the proof principle. A linear map of tensors is fixed by its values on pure
    tensors S.pure f = ⨂ₜ i, f i (ext_pure, an ext lemma), and a property of all tensors follows
    from the pure case (inductionOn_pure). Maps that commute with the group are built from a check
    on pure tensors (equivOfPure, map_smul_of_pure).
  • The action is a Mathlib representation. The group acts index by index,
    Λ • (u ⊗ α) = Λu ⊗ (Λ⁻¹)ᵀα (smul_pure). Mathlib has the representation on the tensor product
    of two representations, but not of a family. Representation.piTprod, added in ForMathlib, is
    that representation on ⨂ i, M i. tensorRep is the action as a Representation, and maps
    that commute with it are Mathlib's Representation.Equiv and Representation.IntertwiningMap,
    so the invariance of a tensor built from invariant pieces follows from map_invariant.
  • Mathlib's maps of ⨂ as maps of representations. ForMathlib proves that applying maps at
    the factors (PiTensorProduct.map, congr), reordering (reindex), joining two families
    (tmulEquivDep), a single factor (subsingletonEquiv) and the contraction of pairs of factors
    (contrPairs, new) commute with piTprod. Later pieces build reindexing, products and
    contraction of tensors on these.
  • The action Λ • T is scoped. The instance distribMulAction is scoped to Tensor, so
    Λ • T needs open scoped Tensor. It has high priority there, since Mathlib gives some groups,
    such as Circle and ℂˣ, a scalar action on every ℂ-module.
  • Components from Mathlib's basis. The components T^μ_νρ are coordinates in
    Basis.piTensorProduct (tensorBasis). The matrix of PiTensorProduct.map is the Kronecker
    product of the matrices at the factors (toMatrix_map_apply, Mathlib has two factors), so
    tensorBasis_repr_smul gives the textbook law
    (ΛT)^μ_νρ = Λ^μ_σ (Λ⁻¹)^τ_ν (Λ⁻¹)^λ_ρ T^σ_τλ.
  • Maps at the indices. mapIndices applies a linear map at every index, through Mathlib's
    PiTensorProduct.map, and mapAt applies one at a single index, with the identity elsewhere.
  • General results in ForMathlib. Every result that does not mention species is stated for
    Mathlib's PiTensorProduct and Representation in ForMathlib, and the tensor lemmas are its
    transports. The two ForMathlib files come whole with this PR, so some of their results are first
    used in later pieces of the stack.

Added

Physlib/Mathematics/ForMathlib/PiTensorProduct.lean

  • PiTensorProduct.toMatrix_map_apply : the matrix of PiTensorProduct.map is the Kronecker
    product of the matrices.
  • Module.finrank_piTensorProduct : the dimension of ⨂ i, M i is the product of the dimensions.
  • PiTensorProduct.map_eq_id_of_isEmpty : with no factors, every PiTensorProduct.map is the
    identity.
  • PiTensorProduct.contrPairs, PiTensorProduct.contrPairs_tprod : the contraction of the pairs
    of factors chosen by κ ⊕ (J ⊕ J) with a family of pairings.

Physlib/Mathematics/ForMathlib/Representation.lean

  • Representation.IntertwiningMap.map_invariant : an intertwining map sends invariant vectors to
    invariant vectors.
  • Representation.IntertwiningMap.map_one_invariant : an intertwining map from the trivial
    representation picks out an invariant vector.
  • Representation.Equiv.tensorCongr, Representation.Equiv.tensorCongr_tmul : the tensor product
    of two equivalences of representations.
  • Representation.piTprod, Representation.piTprod_apply, Representation.piTprod_tprod : the
    representation on ⨂ i, M i.
  • Representation.IsIntertwiningMap.piTprodMap, Representation.Equiv.piTprodCongr,
    Representation.Equiv.piTprodCongr_tprod : PiTensorProduct.map of intertwining maps.
  • Representation.Equiv.piTprodReindex, Representation.Equiv.piTprodReindex_tprod : reindexing
    the factors along an equivalence of index types.
  • Representation.Equiv.piTprodSum, Representation.Equiv.piTprodSum_tmul : the tensor product
    of the two halves of a family indexed by ι₁ ⊕ ι₂.
  • Representation.Equiv.piTprodOfSubsingleton : a representation as the tensor product of a
    family over a subsingleton index type.
  • Representation.map_piTprod_of_tprod : a semilinear map that commutes with piTprod on pure
    tensors commutes with it everywhere.
  • Representation.IsIntertwiningMap.contrPairs : the contraction of pairs of factors is an
    intertwining map when the pairings are invariant.

Physlib/Mathematics/Tensors/Tensor.lean

  • Tensor : the tensors with colors c, with its additive group and module instances.
  • Species.pure : the pure tensor of a family of vectors.
  • Species.inductionOn_pure, Species.ext_pure : induction and extensionality through pure
    tensors.
  • Species.tensorRep : the action as a Mathlib representation.
  • Species.distribMulAction, Species.smul, Species.smulCommClass, Species.smulCommClass' :
    the scoped instances for Λ • T.
  • Species.smul_pure : the action index by index.
  • Species.intertwiningMap_smul, Species.equiv_smul : maps of representations commute with the
    action.
  • Species.map_smul_of_pure : a map that commutes with the action on pure tensors commutes with
    it everywhere.
  • Species.equivOfPure, Species.equivOfPure_apply : an equivalence of representations from a
    check on pure tensors.
  • Species.equiv_ext_pure : extensionality for equivalences of representations.
  • Species.smul_eq_self_of_isEmpty : a tensor with no indices is invariant.
  • Species.tensorBasis, Species.tensorBasis_apply, Species.tensorBasis_repr_pure : the basis
    of tensors and the components of a pure tensor.
  • The Module.Finite instance, Species.finrank_tensor : the dimension of tensors.
  • Species.tensorBasis_repr_smul : the components of Λ • T.
  • Species.mapIndices, Species.mapIndices_pure, Species.mapIndices_comp,
    Species.mapIndices_mapIndices, Species.mapIndices_id, Species.mapIndices_id_apply,
    Species.mapIndices_smul : a linear map at every index.
  • Species.congrIndices, Species.congrIndices_pure : an equivalence of representations at every
    index.
  • Species.indexMapsAt, Species.indexMapsAt_apply_self, Species.indexMapsAt_apply_ne,
    Species.eq_indexMapsAt, Species.indexMapsAt_rep : a linear map at one index and the identity
    at the others.
  • Species.mapAt, Species.mapAt_pure, Species.mapAt_comp, Species.mapAt_id,
    Species.tensorBasis_repr_mapAt : applying it.
  • Species.congrAt, Species.congrAt_eq_mapAt, Species.congrAt_symm : the same for an
    equivalence of representations, as an equivalence of representations.

Reviewer map

  1. The module doc of Tensor.lean, for the design.
  2. Tensor.lean §A (tensors and pure tensors) and §B (the group action). This is where the design
    lives.
  3. The overview of ForMathlib/Representation.lean, for the gap in Mathlib, then its §C
    (piTprod and the maps that commute with it).
  4. ForMathlib/PiTensorProduct.lean: the Kronecker product, the dimension, and contrPairs on
    the arrangement κ ⊕ (J ⊕ J).
  5. Tensor.lean §C (the basis and components).
  6. Tensor.lean §D (maps at the indices), which later pieces use for lowering at one index.

…nd PiTensorProduct.contrPairs

Co-authored-by: Claude Opus 5.5 <no-reply+claude-opus-5-5@anthropic.com>
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Thank you for this pull-request (PR). If this is your first PR, welcome to the community!

While you wait for a review, note that you can review PRs too; reviewing is not restricted to maintainers. Our review guidelines explain what to look for.

Over time, contributions such as reviews, maintenance and documentation are recorded on contributions.physlib.io.

Three main points:

  • Comment -awaiting-author on its own line to remove that label from your PR.
  • Comment blocked-by-PR or -blocked-by-PR on its own line to add or remove that label, respectively.
  • The first review might take several days to arrive. If in doubt message on the Zulip.

For the author: Please read

Below is what will happen next. Please read carefully if you are not familiar with the process. You may open other PRs while this one is being reviewed, and can stack PRs on top of each other, so don't let these steps slow you down.

  1. Some automated checks will be run on your PR. You can see the results of these checks at the buttom of your PR page. If any of these checks fail, you will need to fix the issues before your PR can be merged. You can learn more about these here, including how to run them locally, which is sometimes quicker than relying on the GitHub Actions. If you have never had a PR merged before, you may have to wait for a reviewer to manually start these checks (this is for security).

  2. A reviewer will look at your PR and may ask you to make changes. This may happen a couple of days after you submit your PR, so you may need to be patient. But it should not be longer than that - if it is please bring it to the attention of the community on the Zulip. The level of review will depend on where your PR is submitted. If it is submitted to ./Physlib or ./QuantumInfo, the review will be more thorough than if it is submitted to ./PhyslibAlpha. You can find out more about what the review process is looking for in our review guidelines. If a reviewer adds an awaiting-author label to your PR, address the review comments, then please remove that label by adding a comment with -awaiting-author. This helps us keep track of reviews.

  3. The reviewer will either approve your PR, or request more changes (in which case we return to step 2). Once your PR is approved, it will be merged by a maintainer, this should happen shortly after approval, though you may get more comments at this stage.

Tip: The easiest way to get a fast review is to submit a PR that is small and self-contained, and has clear documentation explaining why things are the way they are in your changes.

If you have any problems or questions, please reach out to the community on the Zulip.

For reviewers: Summary of your PR

Found differences:
@@ Physlib.Mathematics.ForMathlib.PiTensorProduct @@
+ module added Physlib.Mathematics.ForMathlib.PiTensorProduct (+184 -0)
+ added def PiTensorProduct.contrPairs
+ added lemma Module.finrank_piTensorProduct
+ added lemma PiTensorProduct.contrPairs_tprod
+ added lemma PiTensorProduct.map_eq_id_of_isEmpty
+ added lemma PiTensorProduct.toMatrix_map_apply
@@ Physlib.Mathematics.ForMathlib.Representation @@
+ module added Physlib.Mathematics.ForMathlib.Representation (+283 -0)
+ added def Representation.Equiv.piTprodCongr
+ added def Representation.Equiv.piTprodOfSubsingleton
+ added def Representation.Equiv.piTprodReindex
+ added def Representation.Equiv.piTprodSum
+ added def Representation.Equiv.tprodCongr
+ added def Representation.piTprod
+ added lemma Representation.Equiv.piTprodCongr_tprod
+ added lemma Representation.Equiv.piTprodReindex_tprod
+ added lemma Representation.Equiv.piTprodSum_tmul
+ added lemma Representation.Equiv.tprodCongr_tmul
+ added lemma Representation.IsIntertwiningMap.contrPairs
+ added lemma Representation.IsIntertwiningMap.piTprodMap
+ added lemma Representation.map_piTprod_of_tprod
+ added lemma Representation.piTprod_apply
+ added lemma Representation.piTprod_tprod
@@ Physlib.Mathematics.Tensors.Tensor @@
+ module added Physlib.Mathematics.Tensors.Tensor (+552 -0)
  namespaces Tensor, Tensor.Species
+ added abbrev tensorRep
+ added def Tensor
+ added def congrAt
+ added def congrIndices
+ added def equivOfPure
+ added def indexMapsAt
+ added def mapAt
+ added def mapIndices
+ added def pure
+ added def tensorBasis
+ added instance [Finite ι] : Module.Finite k (Tensor S c)
+ added instance distribMulAction
+ added instance smul
+ added instance smulCommClass
+ added instance smulCommClass'
+ added instance {S : Tensor.Species k G K basisIdx} {ι : Type} {c : ι → Tensor.Color K} :
+ added instance {S : Tensor.Species k G K basisIdx} {ι : Type} {c : ι → Tensor.Color K} :
+ added lemma congrAt_eq_mapAt
+ added lemma congrAt_symm
+ added lemma congrIndices_pure
+ added lemma eq_indexMapsAt
+ added lemma equivOfPure_apply
+ added lemma equiv_ext_pure
+ added lemma equiv_smul
+ added lemma ext_pure
+ added lemma finrank_tensor
+ added lemma indexMapsAt_apply_ne
+ added lemma indexMapsAt_apply_self
+ added lemma indexMapsAt_rep
+ added lemma inductionOn_pure
+ added lemma intertwiningMap_smul
+ added lemma mapAt_comp
+ added lemma mapAt_id
+ added lemma mapAt_pure
+ added lemma mapIndices_comp
+ added lemma mapIndices_id
+ added lemma mapIndices_id_apply
+ added lemma mapIndices_mapIndices
+ added lemma mapIndices_pure
+ added lemma mapIndices_smul
+ added lemma map_smul_of_pure
+ added lemma smul_eq_self_of_isEmpty
+ added lemma smul_pure
+ added lemma tensorBasis_apply
+ added lemma tensorBasis_repr_mapAt
+ added lemma tensorBasis_repr_pure
+ added lemma tensorBasis_repr_smul
@@ Physlib @@
! module modified Physlib (+3 -0)
71 differences

The declarations are found by reading the diff as text, without regard for namespaces, so a declaration whose keyword and name are on different lines is missed, and two declarations of the same name in different namespaces are listed as one. A change to a proof, or to the body of a definition, does not appear. See scripts/alpha/github/pr_summary.lean.

Summary of commit b518ef9, remade whenever a commit is pushed.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we have some other results on PiTensorProduct in ./Mathematics, maybe these should be combined with this file.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I couldn't find other PiTensorProduct results under ./Mathematics on master.


A tensor with several indices lies in the tensor product `⨂[R] i, M i` of a family of spaces, one
space `M i` for each index `i`. Here `R` is the scalars, `ℝ` or `ℂ` in physics, and any commutative
semiring in the results below, with a commutative ring in which dimension is well defined, such as a

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

commutative ring in which dimension

I'm not sure what this means here

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, that sentence was unclear. It referred to the hypothesis [StrongRankCondition R] on Module.finrank_piTensorProduct, which turned out not to be needed. Mathlib gives it for every nontrivial commutative ring, so the proof now starts with nontriviality R and the hypothesis is gone. The overview now says that the results hold over any commutative semiring, except the dimension, which needs a commutative ring.


/-- An intertwining map sends an invariant vector to an invariant vector,
`ρ g v = v → σ g (φ v) = φ v`. -/
lemma Representation.IntertwiningMap.map_invariant (φ : ρ.IntertwiningMap σ) {v : V} {g : G}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we need this as it is a simple rw


/-- An intertwining map `φ` from the trivial representation on `k` picks out an invariant vector,
`φ 1`. The hypothesis `φ 1 = v` turns a formula for `φ 1` into the invariance of `v`. -/
lemma Representation.IntertwiningMap.map_one_invariant

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Likewise, don't think we need to add this


/-- The tensor product of two equivalences of representations, `v ⊗ u ↦ φ v ⊗ ψ u`, Mathlib's
`TensorProduct.congr` with the actions `ρ ⊗ τ` and `σ ⊗ π`. -/
noncomputable def Representation.Equiv.tensorCongr (φ : ρ.Equiv σ) (ψ : τ.Equiv π) :

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Representation.Equiv.tprodCongr might be better

Comment thread Physlib/Mathematics/Tensors/Tensor.lean Outdated
/-- The tensors with colors `c : ι → Color K`, the space `⨂[k] i, S.V (c i)`. It is a `def`, not an
`abbrev`, so that goals show `Tensor S c` instead of the product. Mathlib's results on `⨂` apply to
it by unfolding, and its instances are copied from `⨂`. -/
def _root_.Tensor (S : Species k G K basisIdx) {ι : Type} (c : ι → Color K) : Type :=

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would move out of the name space

Comment thread Physlib/Mathematics/Tensors/Tensor.lean Outdated

/-- The action `Λ • T` of the group on tensors, `S.tensorRep c Λ T`, available under
`open scoped Tensor`, where it takes priority over Mathlib's scalar actions. -/
noncomputable abbrev distribMulAction : DistribMulAction G (Tensor S c) :=

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not just make this an instance?

Comment thread Physlib/Mathematics/Tensors/Tensor.lean Outdated
scoped[Tensor] attribute [instance 1100] Tensor.Species.distribMulAction

/-- The scalar multiplication of `distribMulAction`, found before any scalar action of Mathlib. -/
noncomputable abbrev smul : SMul G (Tensor S c) := distribMulAction.toSMul

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Likewise, why not make this an instance?

Comment thread Physlib/Mathematics/Tensors/Tensor.lean Outdated
/-- The tensors with colors `c : ι → Color K`, the space `⨂[k] i, S.V (c i)`. It is a `def`, not an
`abbrev`, so that goals show `Tensor S c` instead of the product. Mathlib's results on `⨂` apply to
it by unfolding, and its instances are copied from `⨂`. -/
def _root_.Tensor (S : Species k G K basisIdx) {ι : Type} (c : ι → Color K) : Type :=

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This might be a bit of a radical design decision, but we could think about whether we actually want to define Tensor, and instead just rely on something like the Tensorial instance on the old method. That way we would not have to prove things more then once.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried this on a branch, rebuilding everything up to Tensorial without a Tensor type. It all works and no proof changes, but it only saves about ten lines. The new Tensorial already avoids the double proofs, since toTensor is now an equivalence of representations, so things like Lorentz.Vector get all the tensor results through it without re-proving anything (the class is in #2014). Keeping Tensor is mainly for readability, since signatures and goals show Tensor S c instead of the full ⨂. So I'd keep it for now.

@jstoobysmith

Copy link
Copy Markdown
Member

awaiting-author

@github-actions github-actions Bot added the awaiting-author A reviewer has asked the author a question or requested changes label Nov 14, 2026
pariandrea and others added 5 commits November 15, 2026 15:44
…othesis

Drop [StrongRankCondition R]. Over a nontrivial commutative ring Mathlib
provides it, and over the zero ring both sides are 1. State the
hypotheses on R plainly in the overview.

Co-authored-by: Claude Opus 5.5 <no-reply+claude-opus-5-5@anthropic.com>
…dCongr

Also tensorCongr_tmul to tprodCongr_tmul, after Representation.tprod.

Co-authored-by: Claude Opus 5.5 <no-reply+claude-opus-5-5@anthropic.com>
…e_invariant

Both are one rewrite with Mathlib's IntertwiningMap.isIntertwining and
have no use in this PR.

Co-authored-by: Claude Opus 5.5 <no-reply+claude-opus-5-5@anthropic.com>
Define Tensor and its AddCommGroup and Module instances before
namespace Tensor, instead of as _root_.Tensor inside it.

Co-authored-by: Claude Opus 5.5 <no-reply+claude-opus-5-5@anthropic.com>
… namespace Tensor

Tensor.distribMulAction, Tensor.smul, Tensor.smulCommClass and
Tensor.smulCommClass' are one-line scoped instances, active under
open scoped Tensor. They replace the abbrevs and lemmas in
Tensor.Species made instances by scoped[Tensor] attribute.

Co-authored-by: Claude Opus 5.5 <no-reply+claude-opus-5-5@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting-author A reviewer has asked the author a question or requested changes large t-mathematics Mathematics

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants